<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:pls="http://www.w3.org/2005/01/pronunciation-lexicon" xmlns:ssml="http://www.w3.org/2001/10/synthesis" xmlns:svg="http://www.w3.org/2000/svg">
  <head>
    <title>Loading Java functions into Scheme</title>
    <link rel="stylesheet" type="text/css" href="docbook-epub.css"/>
    <link rel="stylesheet" type="text/css" href="kawa.css"/>
    <script src="kawa-ebook.js" type="text/javascript"/>
    <meta name="generator" content="DocBook XSL-NS Stylesheets V1.79.1"/>
    <link rel="prev" href="Overall-Index.xhtml" title="Index"/>
    <link rel="next" href="Evaluating-Scheme-expressions-from-Java.xhtml" title="Evaluating Scheme expressions from Java"/>
  </head>
  <body>
    <header/>
    <section class="sect1" title="Loading Java functions into Scheme" epub:type="subchapter" id="Loading-Java-functions-into-Scheme">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both">Loading Java functions into Scheme</h2>
          </div>
        </div>
      </div>
      <p>When <code class="literal">kawa -C</code> compiles (see <a class="link" href="Compiling.xhtml#Files-compilation" title="Compiling to a set of .class files">Files compilation</a>) a Scheme module
it creates a class that implements the <code class="literal">java.lang.Runnable</code> interface.
(Usually it is a class that extends the <code class="literal">gnu.expr.ModuleBody</code>.)
It is actually fairly easy to write similar "modules" by hand in Java,
which is useful when you want to extend Kawa with  new "primitive functions"
written in Java.  For each function you need to create an object that
extends <code class="literal">gnu.mapping.Procedure</code>, and then bind it in the global
environment.  We will look at these two operations.
</p>
      <p>There are multiple ways you can create a <code class="literal">Procedure</code> object.  Below
is a simple example, using the <code class="literal">Procedure1</code> class, which is class
extending <code class="literal">Procedure</code> that can be useful for one-argument
procedure.  You can use other classes to write procedures.  For example
a <code class="literal">ProcedureN</code> takes a variable number of arguments, and you must
define <code class="literal">applyN(Object[] args)</code> method instead of <code class="literal">apply1</code>.
(You may notice that some builtin classes extend <code class="literal">CpsProcedure</code>.
Doing so allows has certain advantages, including support for
full tail-recursion, but it has some costs, and is a bit trickier.)
</p>
      <pre class="screen">import gnu.mapping.*;
import gnu.math.*;
public class MyFunc extends Procedure1
{
  // An "argument" that is part of each procedure instance.
  private Object arg0;

  public MyFunc(String name, Object arg0)
  {
    super(name);
    this.arg0 = arg0;
  }

  public Object apply1 (Object arg1)
  {
    // Here you can so whatever you want. In this example,
    // we return a pair of the argument and arg0.
    return gnu.lists.Pair.make(arg0, arg1);
  }
}
</pre>
      <p>You can create a <code class="literal">MyFunc</code> instance and call it from Java:
</p>
      <pre class="screen">  Procedure myfunc1 = new MyFunc("my-func-1", Boolean.FALSE);
  Object aresult = myfunc1.apply1(some_object);
</pre>
      <p>The name <code class="literal">my-func-1</code> is used when <code class="literal">myfunc1</code> is printed
or when <code class="literal">myfunc1.toString()</code> is called.  However,
the Scheme variable <code class="literal">my-func-1</code> is still not bound.
To define the function to Scheme, we can create
a "module", which is a class intended to be loaded
into the top-level environment.  The provides the definitions to be
loaded, as well as any actions to be performed on loading 
</p>
      <pre class="screen">public class MyModule
{
  // Define a function instance.
  public static final MyFunc myfunc1
    = new MyFunc("my-func-1", IntNum.make(1));
}
</pre>
      <p>If you use Scheme you can use <code class="literal">require</code>:
</p>
      <pre class="screen">#|kawa:1|# (require &lt;MyModule&gt;)
#|kawa:2|# (my-func-1 0)
(1 0)
</pre>
      <p>Note that <code class="literal">require</code> magically defines <code class="literal">my-func-1</code> without
you telling it to.  For each public final
field, the name and value of the field are entered in the
top-level environment when the class is loaded.  (If there are
non-static fields, or the class implements <code class="literal">Runnable</code>, then
an instance of the object is created, if one isn’t available.)
If the field value is a <code class="literal">Procedure</code> (or implements <code class="literal">Named</code>),
then the name bound to the procedure is used instead of the field name.
That is why the variable that gets bound in the Scheme environment is
<code class="literal">my-func-1</code>, not <code class="literal">myfunc1</code>.
</p>
      <p>Instead of <code class="literal">(require &lt;MyModule&gt;)</code>, you can do <code class="literal">(load "MyModule")</code>
or <code class="literal">(load "MyModule.class")</code>.
If you’re not using Scheme, you can use Kawa’s <code class="literal">-f</code> option:
</p>
      <pre class="screen">$ kawa -f MyModule --xquery --
#|kawa:1|# my-func-1(3+4)
&lt;list&gt;1 7&lt;/list&gt;
</pre>
      <p>If you need to do some more complex calculations when a module is loaded,
you can put them in a <code class="literal">run</code> method, and have the module
implement <code class="literal">Runnable</code>:
</p>
      <pre class="screen">public class MyModule implements Runnable
{
  public void run ()
  {
    Interpreter interp = Interpreter.getInterpreter();
    Object arg = Boolean.TRUE;
    interp.defineFunction (new MyFunc ("my-func-t", arg));
    System.err.println("MyModule loaded");
  }
}
</pre>
      <p>Loading <code class="literal">MyModule</code> causes <code class="literal">"MyModule loaded"</code> to be printed,
and <code class="literal">my-func-t</code> to be defined.  Using <code class="literal">Interpreter</code>’s
<code class="literal">defineFunction</code> method is recommended because it does the righ
things even for languages like Common Lisp that use separate
"namespaces" for variables and functions.
</p>
      <p>A final trick is that you can have a <code class="literal">Procedure</code> be its own module:
</p>
      <pre class="screen">import gnu.mapping.*;
import gnu.math.*;
public class MyFunc2 extends Procedure2
{
  public MyFunc(String name)
  {
    super(name);
  }

  public Object apply2 (Object arg1, arg2)
  {
    return gnu.lists.Pair.make(arg1, arg2);
  }

  public static final MyFunc myfunc1 = new MyFunc("my-func-2);
}
</pre>
    </section>
    <footer>
      <div class="navfooter">
        <p>
          Up: <a accesskey="u" href="Objects-Classes-and-Modules.xhtml">Object, Classes and Modules</a></p>
        <p>
        Previous: <a accesskey="p" href="Array-operations.xhtml">Using Java Arrays</a></p>
        <p>
        Next: <a accesskey="n" href="Evaluating-Scheme-expressions-from-Java.xhtml">Evaluating Scheme expressions from Java</a></p>
      </div>
    </footer>
  </body>
</html>
